﻿/* Copyright 2008 dnAnalytics Project.
 *
 * Contributors to this file:
 * Marcus Cuda
 *
 * This file is part of dnAnalytics.  dnAnalytics is licensed under the 
 * Microsoft Public License. See License.txt for a complete copy of the
 * license.
 */

using System.Collections.Generic;

namespace dnAnalytics.LinearAlgebra.IO
{
    /// <summary>
    /// Interface for reading matrices from a file.
    /// </summary>
    public interface IMatrixReader
    {
        /// <summary>
        /// Reads the first matrix from the file or stream.
        /// </summary>
        /// <returns>
        /// If the matrix is stored as a sparse matrix, then a <see cref="SparseMatrix"/> is returned. Otherwise, a <see cref="DenseMatrix"/>
        /// is returned.
        /// </returns>
        Matrix ReadMatrix();
        
        /// <summary>
        /// Reads the first matrix from the file or stream and returns it with the requested <see cref="StorageType"/>.
        /// </summary>
        /// <param name="storageType">The <see cref="StorageType"/> for the new matrix.</param>
        /// <returns>
        /// If the matrix is stored as a sparse matrix, then a <see cref="SparseMatrix"/> is returned. Otherwise, a <see cref="DenseMatrix"/>
        /// is returned.
        /// </returns>
        Matrix ReadMatrix(StorageType storageType);

        /// <summary>
        /// Reads the named matrix from the file or stream.
        /// </summary>
        /// <param name="matrixName">The name of the matrix to read.</param>
        /// <returns>
        /// If the matrix is stored as a sparse matrix, then a <see cref="SparseMatrix"/> is returned. Otherwise, a <see cref="DenseMatrix"/>
        /// is returned. <see langword="null"/> is returned if a matrix with the requests name doesn't exist.
        /// </returns>
        Matrix ReadMatrix(string matrixName);


        /// <summary>
        /// Reads the named matrix from the file or stream and returns it with the requested <see cref="StorageType"/>.
        /// </summary>
        /// <param name="matrixName">The name of the matrix to read.</param>
        /// <param name="storageType">The <see cref="StorageType"/> for the new matrix.</param>
        /// <returns>
        /// If the matrix is stored as a sparse matrix, then a <see cref="SparseMatrix"/> is returned. Otherwise, a <see cref="DenseMatrix"/>
        /// is returned. <see langword="null"/> is returned if a matrix with the requests name doesn't exist.
        /// </returns>
        Matrix ReadMatrix(string matrixName, StorageType storageType);


        /// <summary>
        /// Reads all matrices from the file or stream.
        /// </summary>
        /// <returns>All matrices from the file or stream.</returns>
        Matrix[] ReadMatrices();

        /// <summary>
        /// Reads all matrices from the file or stream and returns them with the requested <see cref="StorageType"/>
        /// </summary>
        /// <param name="storageType">The <see cref="StorageType"/> for the new matrices.</param>
        /// <returns>All matrices from the file or stream.</returns>
        Matrix[] ReadMatrices(StorageType storageType);

        /// <summary>
        /// Reads the named matrices from the file or stream.
        /// </summary>
        /// <param name="names">The names of the matrices to retrieve.</param>
        /// <returns>The named matrices from the file or stream.</returns>
        Matrix[] ReadMatrices(IEnumerable<string> names);

        /// <summary>
        /// Reads the named matrices from the file or stream and returns them with the requested <see cref="StorageType"/>.
        /// </summary>
        /// <param name="names">The names of the matrices to retrieve.</param>
        /// <param name="storageType">The <see cref="StorageType"/> for the new matrices.</param>
        /// <returns>The named matrices from the file or stream.</returns>
        Matrix[] ReadMatrices(IEnumerable<string> names, StorageType storageType);
    }
}